home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 February: Tool Chest / Dev.CD Feb 94.toast / Tool Chest / Development Platforms / AppsToGo / AppsToGo.src / DTS.Lib / =Using CtlHandler.c < prev    next >
Encoding:
Text File  |  1993-06-18  |  8.0 KB  |  183 lines  |  [TEXT/MPS ]
  1. ***** CtlHandler.c usage documentation *****/
  2.  
  3. Purpose:  To simplify and standardize control handling within a window.
  4.  
  5.  
  6. This code implements the new 7.0 human-interface standards for both
  7. TextEdit and List controls.  These standards include the following features:
  8.  
  9. 1) Tabbing between TextEdit and List controls within a window.
  10. 2) Displaying what item is active.  The active TextEdit item is indicated
  11.    by either a blinking caret, or a selection range.
  12. 3) List positioning via the keyboard.  Entries on the keyboard automatically
  13.    select and display the closest List item.  Also, the up and down arrows
  14.    scroll through the list.
  15. 4) Document window scrollbars are handled.
  16.  
  17.  
  18. The main call for handling the control events is:
  19.  
  20. short    IsCtlEvent(WindowPtr window, EventRecord *event, ControlHandle *ctl, short *action);
  21.  
  22. This call handles the following:
  23.     1) Document scrolling.
  24.     2) TextEdit control events.
  25.     3) List control events.
  26.     4) Tabbing between TextEdit and list controls.
  27.     5) Displaying the selected TextEdit or List control.
  28.     6) Buttons.
  29.     7) Radio buttons.
  30.     8) Check boxes.
  31.     9) Popups and other controls.
  32.  
  33. The document content is scrolled automatically.  The updateRgn is set to include the
  34. area scrolled into view and the window update procedure is automatically called.
  35.  
  36. TextEdit and List control events are completely handled.  Since the controls are just
  37. containers for TERecords or ListRecords, all other access is up to the application.
  38.  
  39. Simple buttons are simply tracked.
  40.  
  41. Radio buttons are updated to reflect the new selection.  Radio buttons are handled as
  42. families.  The refCon field holds the family number.  For any given family, there can
  43. only be one selected radio button.  When a new one is clicked on, the old selected
  44. radio button is deselected automatically.
  45.  
  46. Check boxes are simply toggled on and off, as there is no family relationship between
  47. checkboxes.
  48.  
  49. Popups are simply tracked.  To determine what the popup choice is, the popup control
  50. value will have to be retreived.
  51.  
  52. The return value of IsCtlEvent is non-zero if the event was handled.  The values are
  53. as follows:
  54.  
  55. 0x8000:                IsCtlEvent() scrolled the document.  The constant kScrollEvent is defined as
  56.                     0x8000 for this purpose.
  57. 0:                    IsCtlEvent didn't handle the event.
  58. any other value:    The control number of the control that handled the event.  Remember that
  59.                     a TextEdit control may actually consist of up to 3 controls.  There is the
  60.                     main container control for the TERecord.  There may also be 1 or 2 scrollbar
  61.                     controls that are related to the TERecord.  The control number reflects which
  62.                     control was hit.  This allows determination as to whether or not the scrollbar
  63.                     was hit.
  64.  
  65. Just because a control number was returned doesn't mean that a control handle was returned.
  66. If an inactive scrollbar is clicked on, then FindControl() returns nil, instead of the
  67. control handle (really).  The control that is returned is what FindControl returns, and
  68. therefore it is possibly nil.
  69.  
  70. For TextEdit and List controls, IsCtlEvent simply calls CTEClick(), CTEKey(), CLClick() or
  71. CLKey().  The value returned as the action depends on which function was called.  The true/false
  72. returned by these functions as to whether or not the control handled the event is expanded to
  73. be the control number.  If false is returned by any of these functions, then IsCtlEvent()
  74. returns 0 for the control number.
  75.  
  76. IsCtlEvent() has no way of determining if you are actually using TextEdit or List controls.
  77. Since it has to make function calls service these controls, code may get linked into your
  78. application that you don't need.  To prevent this, IsCtlEvent() calls the appropriate
  79. functions by function pointer.  The default functions are just stub functions that return
  80. appropriate results as if there were no such controls.  This allows IsCtlEvent() to handle
  81. the case where these controls aren't used without linking in a bunch of code.
  82.  
  83. So what about the case where you DO want to use these controls?  To create one of these
  84. controls, you have to call either CTENew() or CLNew(), for TextEdit and List controls,
  85. respectively.
  86.  
  87. When CTENew() is called, it calls CTEInitialize().  CTEInitialize() replaces all
  88. of the stub function procedure pointers with pointers to the actual functions.
  89. If you call CTENew(), then CTENew() will get linked in.  Since CTENew() calls
  90. CTEInitialize(), CTEInitialize() will get linked in.  Since it references the actual
  91. code, the actual code will get linked in.  This allows you to not have to worry about
  92. specific implementations linking in too much code.  If you call it, it will link.  The
  93. above process is also done for List controls.
  94.  
  95.  
  96.  
  97. The remaining functions aren't nearly as interesting, but they can prove to be useful.
  98. These are:
  99.  
  100. short    CNum2Ctl(WindowPtr window, short ctlNum, ControlHandle *ctl);
  101.  
  102. This function converts a control number to a control handle.  The function
  103. simply walks the window's control list counting down until it has reached
  104. the right control number.  It also returns the number of controls traversed.
  105. While often this will be the same as the control number passed in, if the
  106. number passed in is greater than the number of controls in the list, then
  107. the number returned is the number of controls in the list.
  108.  
  109. NOTE:    Now that controls can have styles applied to them, controls can have a fixed
  110.         control ID.  If a control has a style, and the ctlID field if the style is
  111.         non-zero, then that control has a fixed control ID.  due to this, CNum2Ctl
  112.         first scans all of the controls for a control sith a style that has the
  113.         designated ctlID.  If one is found, then that's the control returned.  If none
  114.         is found, then the behavior for this function is as before.  This allows for
  115.         backwards-compatibility.
  116.  
  117.  
  118. short    Ctl2CNum(ControlHandle ctl);
  119.  
  120. Convert a control handle to a control number.  This allows you to convert what
  121. is normally a runtime variable into something that can be equated to a constant,
  122. thus allowing you to code your control handling into case statements.  This function
  123. does the opposite of CNum2Ctl.
  124.  
  125.  
  126.  
  127. void    DoCtlActivate(WindowPtr window)
  128.  
  129. This reactivates the TextEdit or List control that was active for a particular window.
  130. When a window is moved from the front, the controls are supposed to become inactive.
  131. This is handled, but the control that was last active for a window is remembered.
  132. When the window is brought to the front, that particular control can be reactivated
  133. by calling DoCtlActivate().
  134.  
  135.  
  136.  
  137. short    GetButtonVariant(ControlHandle ctl);
  138.  
  139. This returns the variant type for a button control, independent of which system software
  140. you are running.
  141.  
  142.  
  143.  
  144. void    GetCheckBoxValues(WindowPtr window, Boolean checkBoxVal[]);
  145.  
  146. This returns all of the checkbox values for a window all at once.  The array has
  147. to have at least as many elements as there are checkboxes in the window.  Once
  148. this call is made, you can simply reference the value in the appropriate position
  149. in the array.
  150.  
  151.  
  152.  
  153. short    GetRadioButtonChoice(WindowPtr window, short famNum);
  154.  
  155. Given a particular family number, return which radio button is the currently selected
  156. button.  If the requested family isn't found, or there are no selected radio buttons
  157. in the family, -1 is returned.  If the family is found, the control number of the the
  158. selected radio button minus the control number of the first in the family is returned.
  159. This means that for most situations, you will simply get an integer from 0-N for the
  160. radio button selection, as in most cases, the radio buttons will be sequential in the
  161. control list.
  162.  
  163.  
  164.  
  165. short    HandleScrollEvent(WindowPtr window, EventRecord *event, ControlHandle *retCtl, short *action);
  166.  
  167. This is the function that IsCtlEvent uses to handle the document scrolling.  You can
  168. call it directly if you wish.  You may wish to do this if your windows don't have any
  169. content controls, and all you need is the document scrolling support.  By calling it
  170. directly, instead of by calling it through IsCtlEvent(), you will link in less code
  171. into your application.
  172.  
  173.  
  174.  
  175. ControlHandle    CDataNext(WindowPtr window, ControlHandle ctl);
  176.  
  177. A Data control was added to the set of control types.  This function allows you to get
  178. the next data control for a window.
  179.  
  180.  
  181.  
  182.  
  183.